---
description: Instructions for developing and contributing to the theme
date: 27 January 2020
---

<!-- Page title left out so it can be generated -->

<PageDescription>

Use this guide to contribute to the theme. We’ll show you how to get the
development environment set up as quickly as possible so you can start
contributing.

</PageDescription>

<AnchorLinks>
  <AnchorLink>Project setup</AnchorLink>
  <AnchorLink>Development</AnchorLink>
  <AnchorLink>Work in a branch</AnchorLink>
  <AnchorLink>Sass and CSS Modules</AnchorLink>
  <AnchorLink>VS Code</AnchorLink>
  <AnchorLink>Test pages</AnchorLink>
  <AnchorLink>Publishing</AnchorLink>
</AnchorLinks>

## Project setup

1. Go to
   [gatsby-theme-carbon](https://github.com/carbon-design-system/gatsby-theme-carbon)
   and click the `Fork` button in the top-right corner.

2. After it’s finished, click on the `Clone or Download` button and copy the
   contents.

3. In your terminal, clone the repo into your directory of choice

```sh
git clone [PASTE_URL_HERE]
cd gatsby-theme-carbon
```

4. When you clone your forked repo the `origin` is set to your fork by default.
   You’ll want to add a remote that points to the upstream repo.

```sh
git remote add upstream git@github.com:carbon-design-system/gatsby-theme-carbon.git
```

5. In your terminal, verify that the remotes have been set

```sh
git remote -v
```

## Development

We use [yarn](https://yarnpkg.com/lang/en/docs/install/) and yarn workspaces to
develop the Carbon Gatsby theme. This allows us to have a development
environment that’s closely linked to the theme with minimal setup. Run
`yarn install` to install all of the projects dependencies.

This project has two packages: the actual theme package (`gatsby-theme-carbon`)
and the `example` package. The example package emulates a project which uses the
theme. Its only dependencies are Gatsby, React, and the adjacent theme package.
The `example` package also serves as the theme’s documentation and
[website](https://gatsby-theme-carbon.now.sh); it’s deployed on every merge to
main.

New theme development will happen in the theme package while documentation and
testing of that change will occur through changes in the example directory.

### Development scripts

- `yarn dev` – start the development environment
- `yarn dev:clean` – clear cache and restart dev
- `yarn format` – format your code with prettier
- `yarn lint` - check for errors in your javascript
- `yarn test:prefix` – build and serve with a path prefix

## Work in a branch

You should always start a new project by pulling upstream changes into main and
then creating a new branch. This workflow ensures you don’t accidentally commit
anything to your main branch and get stuck when trying to open a pull request.

```sh
git checkout main
git pull upstream main
git checkout -b my-branch-name
```

### Commit messages

For commit messages we use
[Angular commit conventions](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#allowed-type)
to dictate whether a commit is for a feature, fix, docs, etc. You need to prefix
your commits with one of the following:

- feat (feature)
- fix (bug fix)
- docs (documentation)
- style (formatting, missing semi colons, …)
- refactor
- test (when adding missing tests)
- chore (maintain)

```sh
git commit -m "chore: this is a test commit message"
```

### Opening a Pull request

When you’re ready to open a pull request, push to your origin remote.

```sh
git push origin my-branch-name
```

You’ll get a message in your terminal with a URL to open up a pull request in
the upstream repository. Navigate to that URL and be sure to give a detailed
summary of your pull request in the title and body section of the form.

## Sass and CSS Modules

For internal theme components we use
[Sass](https://sass-lang.com/documentation/syntax) and
[CSS Modules](https://github.com/css-modules/css-modules#css-modules). This
allows us to take advantage of the Carbon Design System resources while not
worrying about className collisions. By default, each `.scss` file will be
supplied with all of the Carbon Sass
[variables](https://github.com/carbon-design-system/carbon/blob/main/packages/components/src/globals/scss/_vars.scss):
color, spacing, theme, and motion, as well as type and layout mixins, are
imported automatically.

You should colocate your stylesheet with the component(s) that import it. If the
component is `TreeView` then the stylesheet should be `TreeView.module.scss`.
All contained within the `TreeView` directory.

### CSS Modules

You don’t need to prefix your classes as CSS Modules will generate unique class
names for you. Import the class from the `.scss` file.

```scss path=TreeView.module.scss
.treeView {
  color: $text-01;
}
```

```jsx path=TreeView.js
import { treeView } from './style.css';

const TreeView = (props) => <div className={treeView} />;
```

For conditionally applying class names, use the `classname` library. Note how
we’re using a
[computed property name](https://tylermcginnis.com/computed-property-names/) for
the property being based to `cx`. That’s because the className isn’t literally
`"long"` it’s a value generated by CSS Modules and placed in the `long`
variable.

```jsx path=TreeView.js
import cx from 'classname';
import { treeView, long } from './style.css';

const TreeView = (props) => {
  const className = cx(treeView, {
    [long]: props.long,
  });
  const TreeView = (props) => <div className={className} />;
};
```

If you need to target a global class not processed by CSS Modules, you can do so
with the
[global selector](https://github.com/css-modules/css-modules#exceptions).

```scss
:global(.bx--grid) .codeBlock {
  @include carbon--type-style('code-01');
}
```

## VS Code

To get linting error feedback while writing javascript and SCSS in VS Code,
install the
[stylelint](https://marketplace.visualstudio.com/items?itemName=shinnn.stylelint)
and
[ESlint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
extensions. We use ESLint’s Prettier rules to format and lint all of our
JavaScript in one pass. To get your code to format properly on save, add the
following to a `.vscode/settings.json` in the root of your project

```json path=.vscode/settings.json
{
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.formatOnSave": false
  },
  "[javascriptreact]": {
    "editor.formatOnSave": false
  },
  "eslint.autoFixOnSave": true,
  "prettier.disableLanguages": ["javascript", "javascriptreact"]
}
```

To lint the entire project and get errors in your `Problems` tray, you can add
the following to a `.vscode/tasks.json` file in the root of your project. You
can run these tasks with `cmd+shift+d`

```json path=.vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "lint:js",
      "problemMatcher": "$eslint-stylish"
    },
    {
      "type": "npm",
      "script": "lint:scss",
      "problemMatcher": {
        "owner": "stylelint",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "pattern": [
          {
            "regexp": "^([^\\s].*)$",
            "file": 1
          },
          {
            "regexp": "^\\s+(\\d+):(\\d+)\\s+(✖|warning)\\s+(.*)\\s\\s+(.*)$",
            "line": 1,
            "column": 2,
            "severity": 3,
            "message": 4,
            "code": 5,
            "loop": true
          }
        ]
      }
    }
  ]
}
```

## Test pages

If you want to add examples of what you are working on or see changes you’ve
made, you can add an MDX file to `packages/src/pages/test` that will be visible
at `(your-server-name)/test/(added-file)` during development. If you do add a
page to the `/test` directory, update the below list with the file you added and
its purpose to be included with your pull request.

- [`Spacing audit`](/test/spacing-audit): use this page to test spacing around
  components when combined in common patterns.

## Publishing

1. Pull the latest from the main branch, usually by running
   `git pull upstream main` on your local machine.
2. From the root of the package run `yarn release`.
3. Follow the prompts accordingly.
4. In the project’s
   [release tab](https://github.com/carbon-design-system/gatsby-theme-carbon/releases),
   edit the new release to include a summary of new changes.
